TSG/Storage: add testable metadata markers + live-validated enhancements (4 articles) - #343
Open
John Neemes (1008covingtonlane) wants to merge 3 commits into
Open
Conversation
…ments Adds tsg-metadata/v1 markers to all four TSG/Storage articles and hardens each from live HaaS validation: AddPhysicalDisks (L3 reversible add and remove cycle), CanPoolFalse (title-case CannotPoolReason strings, UniqueId-safe manual add), StoragePoolCapacityThreshold (fixed vs thin thesis, forced power-off gate, verified on-box fault strings), and the Support Diagnostics reference (Include-token matrix). All four reach a perfect 13-persona panel at lint A. Markers are hidden HTML comments and do not change rendered content. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
John Neemes (1008covingtonlane)
requested review from
Alex Burns (AlBurns-MSFT) and
Adam Rudell (arudell)
and
a balanced review from Copilot
August 17, 2026 22:14
Copilot started reviewing on behalf of
John Neemes (1008covingtonlane)
August 17, 2026 22:17
View session
Contributor
There was a problem hiding this comment.
Pull request overview
Adds testable metadata and validated storage guidance improvements across four Azure Local articles.
Changes:
- Adds
tsg-metadata/v1markers for pipeline discovery. - Expands safety, validation, evidence, and escalation guidance.
- Corrects disk-state terminology and diagnostic output details.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
HowTo-Storage-AddPhysicalDisksToS2DPool.md |
Strengthens safe disk-add and verification procedures. |
Troubleshoot-Storage-PhysicalDiskCanPoolFalse.md |
Expands reason-based diagnosis and evidence collection. |
Troubleshoot-Storage-StoragePoolCapacityThreshold.md |
Clarifies fixed/thin remediation and validation. |
Troubleshooting-Storage-With-Support-Diagnostics-Tool.md |
Adds a comprehensive diagnostic command reference. |
Suppressed comments (1)
TSG/Storage/Troubleshoot-Storage-PhysicalDiskCanPoolFalse.md:482
- What: the second transcript-copy block again filters only
.txt,.log,.etl, and.zip, while this cmdlet writes its transcript as CSV. Why: the physical-extent run's native evidence is never copied, and a later same-day run can overwrite it. How: select the newly modifiedTraceOutput_*.csvand save it with a distinct name.
# Copy the native tool transcript for this run into the evidence package as well.
Get-ChildItem -Path $diagWorkingDir -Recurse -File |
Where-Object { $_.LastWriteTime -ge $extentStart -and $_.Extension -in '.txt','.log','.etl','.zip' } |
ForEach-Object { Copy-Item -Path $_.FullName -Destination $evidenceRoot -Force }
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
1. The Support Diagnostics evidence copy now resolves the tool's own working directory via Get-AzsSupportWorkingDirectory (falling back to the current directory only if unavailable) instead of assuming the shell CWD, and both copy blocks include .csv so the native Start-AzsSupportStorageDiagnostic_TraceOutput_*.csv transcript is captured rather than silently omitted. 2. The "verification stuck" branch now links the companion guide by relative path (Troubleshoot-Storage-PhysicalDiskVerificationStuck.md) and adds an explicit Microsoft Support (CSS) fallback, so an operator has an actionable next step even before that companion article is published. The stale "PR 333 ownership" table-cell reference is replaced with the same CSS escalation.
The manual Add-PhysicalDisk step (Step 4) is state-changing (it changes storage pool membership) but carried no canonical risk label, while the sibling Troubleshoot-Storage-PhysicalDiskCanPoolFalse.md labels the identical manual pool add [MEDIUM RISK] and the contributor guidance requires labeling state-changing commands. Add the label to match. (The step already gates with a count-match throw, -WhatIf preview, and an explicit operator confirmation.)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds machine-readable test metadata (the
tsg-metadata/v1marker) to all four content articles underTSG/Storage, alongside targeted enhancements validated against live Storage Spaces Direct clusters in an internal HaaS lab. This lets the directory be discovered and automatically tested by the metadata-driven pipeline.Each article now carries a hidden
<!-- tsg-metadata ... -->marker declaring document type, detector, reproduction substrate, live-validation fidelity, and a backing spec reference. Content was hardened for reader usability across a 13-persona review (leadership skim, first-day technician, CSS engineer, partner SI, OEM, and others), and every article reached a perfect panel with no remaining required change.Articles
CanPoolboolean vsIn a Poolreason)CannotPoolReasonvalues corrected to the exact title-case strings the product emits (In a Pool,Insufficient Capacity, and others); scope banner; beginner off-ramp before the destructive reset-Includetoken matrix run read-only; glossary; corrected all-PASS escalation target; PhysicalExtentCheck edge output documentedValidation
Every article was live-exercised read-only where safe, and for AddPhysicalDisks with a fully reversible scratch-disk add-and-remove that restored the pool byte-identical to its pre-test baseline. No production or customer system was used. The exact commands, observed output shapes, and per-run evidence live in the backing test specs.
Notes for reviewers
tsg-metadata.schema.jsonthese markers validate against is added in the companion Templates PR (Forge and standardize public TSG templates #342); that one should merge first./cc Alex Burns (@AlBurns-MSFT) Adam Rudell (@arudell) Meghay (@mejayara) for review.